IRIX Base Documentation 2002 November/SGI IRIX Base Documentation 2002 November.iso/usr/share/catman/p_man/cat3x/fam.z/fam

Text File | 2002-10-03 | 20.3 KB | 397 lines

FFFFAAAAMMMM((((3333XXXX))))                                                                FFFFAAAAMMMM((((3333XXXX))))



NNNNAAAAMMMMEEEE
     fam - File Alteration Monitor (FAM) library routines

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     ####iiiinnnncccclllluuuuddddeeee <<<<ffffaaaammmm....hhhh>>>>

     eeeexxxxtttteeeerrrrnnnn iiiinnnntttt FFFFAAAAMMMMOOOOppppeeeennnn((((FFFFAAAAMMMMCCCCoooonnnnnnnneeeeccccttttiiiioooonnnn**** ffffcccc))));;;;

     eeeexxxxtttteeeerrrrnnnn iiiinnnntttt FFFFAAAAMMMMCCCClllloooosssseeee((((FFFFAAAAMMMMCCCCoooonnnnnnnneeeeccccttttiiiioooonnnn**** ffffcccc))));;;;

     eeeexxxxtttteeeerrrrnnnn iiiinnnntttt FFFFAAAAMMMMMMMMoooonnnniiiittttoooorrrrDDDDiiiirrrreeeeccccttttoooorrrryyyy((((FFFFAAAAMMMMCCCCoooonnnnnnnneeeeccccttttiiiioooonnnn ****ffffcccc,,,,
                                    cccchhhhaaaarrrr ****ffffiiiilllleeeennnnaaaammmmeeee,,,,
                                    FFFFAAAAMMMMRRRReeeeqqqquuuueeeesssstttt**** ffffrrrr,,,,
                                    vvvvooooiiiidddd**** uuuusssseeeerrrrDDDDaaaattttaaaa))));;;;

     eeeexxxxtttteeeerrrrnnnn iiiinnnntttt FFFFAAAAMMMMMMMMoooonnnniiiittttoooorrrrFFFFiiiilllleeee((((FFFFAAAAMMMMCCCCoooonnnnnnnneeeeccccttttiiiioooonnnn ****ffffcccc,,,,
                               cccchhhhaaaarrrr ****ffffiiiilllleeeennnnaaaammmmeeee,,,,
                               FFFFAAAAMMMMRRRReeeeqqqquuuueeeesssstttt**** ffffrrrr,,,,
                               vvvvooooiiiidddd**** uuuusssseeeerrrrDDDDaaaattttaaaa))));;;;

     iiiinnnntttt FFFFAAAAMMMMSSSSuuuussssppppeeeennnnddddMMMMoooonnnniiiittttoooorrrr((((FFFFAAAAMMMMCCCCoooonnnnnnnneeeeccccttttiiiioooonnnn ****ffffcccc,,,, FFFFAAAAMMMMRRRReeeeqqqquuuueeeesssstttt ****ffffrrrr))));;;;

     iiiinnnntttt FFFFAAAAMMMMRRRReeeessssuuuummmmeeeeMMMMoooonnnniiiittttoooorrrr((((FFFFAAAAMMMMCCCCoooonnnnnnnneeeeccccttttiiiioooonnnn ****ffffcccc,,,, FFFFAAAAMMMMRRRReeeeqqqquuuueeeesssstttt ****ffffrrrr))));;;;

     iiiinnnntttt FFFFAAAAMMMMCCCCaaaannnncccceeeellllMMMMoooonnnniiiittttoooorrrr((((FFFFAAAAMMMMCCCCoooonnnnnnnneeeeccccttttiiiioooonnnn ****ffffcccc,,,, FFFFAAAAMMMMRRRReeeeqqqquuuueeeesssstttt ****ffffrrrr))));;;;

     iiiinnnntttt FFFFAAAAMMMMNNNNeeeexxxxttttEEEEvvvveeeennnntttt((((FFFFAAAAMMMMCCCCoooonnnnnnnneeeeccccttttiiiioooonnnn ****ffffcccc,,,, FFFFAAAAMMMMEEEEvvvveeeennnntttt ****ffffeeee))));;;;

     iiiinnnntttt FFFFAAAAMMMMPPPPeeeennnnddddiiiinnnngggg((((FFFFAAAAMMMMCCCCoooonnnnnnnneeeeccccttttiiiioooonnnn**** ffffcccc))));;;;

     ttttyyyyppppeeeeddddeeeeffff ssssttttrrrruuuucccctttt {{{{
         iiiinnnntttt ffffdddd;;;;
     }}}} FFFFAAAAMMMMCCCCoooonnnnnnnneeeeccccttttiiiioooonnnn;;;;

     ####ddddeeeeffffiiiinnnneeee FFFFAAAAMMMMCCCCOOOONNNNNNNNEEEECCCCTTTTIIIIOOOONNNN____GGGGEEEETTTTFFFFDDDD((((ffffcccc))))      ((((ffffcccc---->>>>ffffdddd))))

     ttttyyyyppppeeeeddddeeeeffff ssssttttrrrruuuucccctttt {{{{
         iiiinnnntttt rrrreeeeqqqqnnnnuuuummmm;;;;
     }}}} FFFFAAAAMMMMRRRReeeeqqqquuuueeeesssstttt;;;;

     eeeennnnuuuummmm FFFFAAAAMMMMCCCCooooddddeeeessss {{{{ FFFFAAAAMMMMCCCChhhhaaaannnnggggeeeedddd====1111,,,, FFFFAAAAMMMMDDDDeeeelllleeeetttteeeedddd====2222,,,, FFFFAAAAMMMMSSSSttttaaaarrrrttttEEEExxxxeeeeccccuuuuttttiiiinnnngggg====3333,,,,
         FFFFAAAAMMMMSSSSttttooooppppEEEExxxxeeeeccccuuuuttttiiiinnnngggg====4444,,,, FFFFAAAAMMMMCCCCrrrreeeeaaaatttteeeedddd====5555,,,, FFFFAAAAMMMMMMMMoooovvvveeeedddd====6666,,,, FFFFAAAAMMMMAAAAcccckkkknnnnoooowwwwlllleeeeddddggggeeee====7777,,,,
         FFFFAAAAMMMMEEEExxxxiiiissssttttssss====8888,,,, FFFFAAAAMMMMEEEEnnnnddddEEEExxxxiiiisssstttt====9999 }}}};;;;

     ttttyyyyppppeeeeddddeeeeffff ssssttttrrrruuuucccctttt {{{{
         FFFFAAAAMMMMCCCCoooonnnnnnnneeeeccccttttiiiioooonnnn**** ffffcccc;;;;
         FFFFAAAAMMMMRRRReeeeqqqquuuueeeesssstttt ffffrrrr;;;;
         cccchhhhaaaarrrr hhhhoooossssttttnnnnaaaammmmeeee[[[[MMMMAAAAXXXXHHHHOOOOSSSSTTTTNNNNAAAAMMMMEEEELLLLEEEENNNN]]]];;;;
         cccchhhhaaaarrrr ffffiiiilllleeeennnnaaaammmmeeee[[[[NNNNAAAAMMMMEEEE____MMMMAAAAXXXX]]]];;;;
         vvvvooooiiiidddd ****uuuusssseeeerrrrddddaaaattttaaaa;;;;
         FFFFAAAAMMMMCCCCooooddddeeeessss ccccooooddddeeee;;;;
     }}}} FFFFAAAAMMMMEEEEvvvveeeennnntttt;;;;



                                                                        PPPPaaaaggggeeee 1111






FFFFAAAAMMMM((((3333XXXX))))                                                                FFFFAAAAMMMM((((3333XXXX))))



     eeeexxxxtttteeeerrrrnnnn iiiinnnntttt FFFFAAAAMMMMEEEErrrrrrrrnnnnoooo;;;;

     eeeexxxxtttteeeerrrrnnnn cccchhhhaaaarrrr ****FFFFaaaammmmEEEErrrrrrrrlllliiiisssstttt[[[[]]]];;;;

DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     _F_A_M monitors files and directories, notifying interested applications of
     changes.  Routines for communicating with the fam(1M) server process are
     found in ``libfam.a'', which is loaded if the option ``-lfam'' is used
     with cc(1) or ld(1).  The library ``libC.a'' (``-lC'') must also be
     specified.

     An application calls routines described here to establish a list of files
     for _f_a_m to monitor.  _F_a_m generates events on a socket to communicate with
     the application.  The _f_a_m process is started when the first connection
     from any application to it is opened.  It exits after all connections to
     it have been closed.

UUUUSSSSIIIINNNNGGGG FFFFAAAAMMMM
     Here are the steps required to use _F_A_M in an application:

     1.   Create a connection to _f_a_m by calling FAMOpen.  This routine will
          pass back a FAMConnection structure used in all _f_a_m procedures.

     2.   Tell _f_a_m which files and directories to monitor by calling
          FAMMonitorFile and FAMMonitorDirectory to express interest in files
          and directories, respectively.

     3.   Select on the _f_a_m socket file descriptor and call FAMPending when
          the _f_a_m socket is active, and FAMNextEvent when FAMPending indicates
          that an event is available.  Alternatively, call FAMPending (or
          FAMNextEvent) periodically to check the socket connection to _f_a_m to
          see if any new information has arrived.  If there are no events
          pending, FAMNextEvent blocks until an event occurs.

     4.   When the application is through monitoring a file or directory, it
          should call FAMCancelMonitor.  If the application wants to
          temporarily suspend monitoring of a file or directory, it may call
          FAMSuspendMonitor.  When the application is ready to start
          monitoring again, it calls FAMResumeMonitor.

     5.   Before the application exits, it should call FAMClose to free
          resources associated with files still being monitored and to close
          the connection to _f_a_m.

DDDDAAAATTTTAAAA SSSSTTTTRRRRUUUUCCCCTTTTUUUURRRREEEESSSS
     TTTThhhheeee FFFFAAAAMMMMCCCCoooonnnnnnnneeeeccccttttiiiioooonnnn SSSSttttrrrruuuuccccttttuuuurrrreeee

     The FAMConnection data structure is created when opening a connection to
     _F_A_M.  Subsequently it is passed into all _F_A_M procedures.  This structure
     has all the information in it to communicate to _f_a_m.





                                                                        PPPPaaaaggggeeee 2222






FFFFAAAAMMMM((((3333XXXX))))                                                                FFFFAAAAMMMM((((3333XXXX))))



     Use the macro FAMCONNECTION_GETFD to access the file descriptor inside
     the FAMConnection, rather than accessing it directly.

     TTTThhhheeee FFFFAAAAMMMMRRRReeeeqqqquuuueeeesssstttt SSSSttttrrrruuuuccccttttuuuurrrreeee

     When _f_a_m is called on to monitor a file, it passes back a FAMRequest
     structure.  This structure uniquely identifies the request so that it may
     be cancelled, using FAMCancelMonitor or suspended, using
     FAMSuspendMonitor.

     TTTThhhheeee FFFFAAAAMMMMEEEEvvvveeeennnntttt SSSSttttrrrruuuuccccttttuuuurrrreeee

     Changes to files and directories are encoded in the FAMEvent structure.
     The _c_o_d_e field of this structure contains one of the following
     enumeration constants:

     FAMChanged
              Some value which can be obtained with fstat(1) changed for a
              file or directory being monitored.

     FAMDeleted
              A file or directory being monitored was deleted or its name was
              changed.  This event is also generated when monitoring starts on
              a nonexistent file or directory.

     FAMStartExecuting
              An executable file or shared library being monitored started
              executing.  If multiple processes execute the same file, this
              event only occurs when the first process starts.

     FAMStopExecuting
              An executable file being monitored which was running finished.
              If multiple processes from an executable are running, this event
              is only generated when the last one finishes.

     FAMCreated
              A file was created in a directory being monitored.  Note: this
              event is only generated for files created directly in a
              directory being monitored; subdirectories are not automatically
              monitored.

     FAMMoved FAMMoved events never occur.  The name remains defined so that
              programs that reference it will still compile.

     FAMAcknowledge
              After a FAMCancelMonitor, _f_a_m generates a FAMAcknowledge event.
              Also, if an invalid pathname is specified, _f_a_m  generates a
              FAMAcknowledge event.

     FAMExists
              When the application requests a file be monitored, _f_a_m generates
              a FAMExists event for that file.  When the application requests



                                                                        PPPPaaaaggggeeee 3333






FFFFAAAAMMMM((((3333XXXX))))                                                                FFFFAAAAMMMM((((3333XXXX))))



              a directory be monitored, _f_a_m generates a FAMExists event for
              that directory and every file directly contained in that
              directory.

     FAMEndExist
              When the application requests a file directory be monitored, a
              series of FAMExists events is generated as described above.
              After the last FAMExists message, _f_a_m generates a FAMEndExist
              message.

     If a FAM event applies to a file or directory being monitored, the
     FAMEvent's _f_i_l_e_n_a_m_e field contains the full pathname that was passed to
     fam.  If an event applies to an entry in a monitored directory, the
     _f_i_l_e_n_a_m_e field contains the relative path only.  For example, if the
     directory /_u_s_r/_t_m_p/_x_y_z_z_y were monitored, and the file
     /_u_s_r/_t_m_p/_x_y_z_z_y/_p_l_u_g_h  were deleted, a FAMDeleted event would be generated
     containing "plugh" in _f_i_l_e_n_a_m_e.  If the directory itself were deleted,
     _f_i_l_e_n_a_m_e would contain "/usr/tmp/xyzzy".

PPPPRRRROOOOCCCCEEEEDDDDUUUURRRREEEESSSS
     FFFFAAAAMMMMOOOOppppeeeennnn,,,, FFFFAAAAMMMMCCCClllloooosssseeee

     The application opens a connection to _f_a_m by calling FAMOpen.  FAMOpen
     initializes the FAMConnection structure passed in to it and returns 0 if
     successful, otherwise -1.  The variable char* appName should be set to
     the name of your application. The FAMConnection structure is passed to
     all subsequent _F_A_M procedure calls.

     FAMClose frees resources associated with files still being monitored and
     closes a _f_a_m connection.  It returns 0 if successful and -1 otherwise.

     FFFFAAAAMMMMMMMMoooonnnniiiittttoooorrrrDDDDiiiirrrreeeeccccttttoooorrrryyyy,,,, FFFFAAAAMMMMMMMMoooonnnniiiittttoooorrrrFFFFiiiilllleeee

     FAMMonitorDirectory and FAMMonitorFile tell _F_A_M to start monitoring a
     directory or file, respectively.  The parameters to this function are a
     FAMConnection (initialized by FAMOpen), a FAMRequest structure, a
     filename and a user data pointer.  The FAMRequest structure is modified
     to subsequently identify this request.  When the file or directory
     changes, a _F_A_M event structure will be generated.  The application can
     retrieve this structure by calling FAMNextEvent (see description under
     FAMNextEvent).

     FAMMonitorDirectory monitors changes that happens to the contents of the
     directory (as well as the directory file itself); FAMMonitorFile monitors
     only what happens to a particular file.  Both routines return 0 if
     successful and -1 otherwise.

     The filename argument must be a full pathname.

     FFFFAAAAMMMMSSSSuuuussssppppeeeennnnddddMMMMoooonnnniiiittttoooorrrr,,,, FFFFAAAAMMMMRRRReeeessssuuuummmmeeeeMMMMoooonnnniiiittttoooorrrr





                                                                        PPPPaaaaggggeeee 4444






FFFFAAAAMMMM((((3333XXXX))))                                                                FFFFAAAAMMMM((((3333XXXX))))



     FAMSuspendMonitor temporarily suspends monitoring of files or
     directories.  This is useful when an application is not displaying
     information about files, when it is iconified, for example.
     FAMResumeMonitor signals _f_a_m to start monitoring the file or directory
     again.  Changes which occur while monitoring is suspended are enqueued
     and delivered when monitoring is resumed.

     Both of these routines take a FAMConnection and a FAMRequest structure.
     The FAMRequest Structure is returned from the FAMMonitorFile or
     FAMMonitorDirectory routines and return 0 if successful and -1 otherwise.

     Because fam runs as an asynchronous process, FAMNextEvent may return a
     few events regarding a given request after that request has been
     suspended.

     FFFFAAAAMMMMCCCCaaaannnncccceeeellllMMMMoooonnnniiiittttoooorrrr

     When an application is through monitoring a file or directory, it should
     call FAMCancelMonitor.  This routine will signal _f_a_m not to monitor this
     directory anymore.  The FAMRequest structure is returned from the
     FAMMonitorFile or FAMMonitorDirectory routines.  FAMCancelMonitor returns
     0 if successful and -1 otherwise.

     FFFFAAAAMMMMPPPPeeeennnnddddiiiinnnngggg,,,, FFFFAAAAMMMMNNNNeeeexxxxttttEEEEvvvveeeennnntttt

     FAMPending returns 1 if an event is waiting and 0 if no event is waiting.
     It also returns 1 if an error has been encountered.  This routine returns
     immediately to the caller.

     FAMNextEvent will get the next _F_A_M event.  If there are no _F_A_M events
     waiting, then the calling application blocks until a _F_A_M event is
     received.  If blocking is not desirable, call FAMPending before
     FAMNextEvent, and only call FAMNextEvent when FAMPending says an event is
     available.

     There are two ways to for applications to receive _F_A_M events:

     1. The Select approach - The application selects on the file
         descriptor returned from FAMOpen, in the FAMConnection structure.
         When this file descriptor becomes active, the application calls
         FAMPending to determine whether a complete event is ready, and
         FAMNextEvent to retrieve the pending _F_A_M event.

     2. The Polling approach - The application calls FAMPending
         periodically (usually when the system is waiting for input).
         When FAMPending returns 1, the application calls FAMNextEvent to
         retrieve the pending _F_A_M  event.

     FAMNextEvent reads any information that is on the _f_a_m socket, and returns
     it to the application in the form of a FAMEvent.





                                                                        PPPPaaaaggggeeee 5555






FFFFAAAAMMMM((((3333XXXX))))                                                                FFFFAAAAMMMM((((3333XXXX))))



     FAMNextEvent returns 1 if successful and -1 otherwise.



SSSSEEEEEEEE AAAALLLLSSSSOOOO
     fam(1M).

BBBBUUUUGGGGSSSS
     The FAMMoved event is not currently supported.

     FAMNextEvent may not initialize the FAMEvent's filename field for
     FAMEndExist and FAMAcknowledge events.  Use the request number to
     determine the file or directory to which those events refer.

     FAMErrno and FamErrlist are not set when errors occur.

     When a shell script is run, notification is generated for the shell
     executing the script, typically sh(1) or csh(1).

     Each process is limited to 1000 active requests at a time.



































                                                                        PPPPaaaaggggeeee 6666